﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="../helpproject.xsl" ?>
<topic template="Default" lasteditedby="Geert" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../helpproject.xsd">
  <title translate="true">PleaseWaitService</title>
  <keywords>
    <keyword translate="true">IPleaseWaitService</keyword>
    <keyword translate="true">MVVM</keyword>
    <keyword translate="true">PleaseWaitService</keyword>
    <keyword translate="true">Services</keyword>
  </keywords>
  <body>
    <header>
      <para styleclass="Heading1"><text styleclass="Heading1" translate="true">PleaseWaitService</text></para>
    </header>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Services_IPleaseWaitService" styleclass="Normal" translate="true">IPleaseWaitService</link><text styleclass="Normal" translate="true"> allows a developer to show a please wait message (a.k.a. busy indicator) from a view model. </text></para>
    <para styleclass="Normal"><table styleclass="Default" rowcount="8" colcount="2">
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" style="font-weight:bold;" translate="true">Feature</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><text styleclass="Normal (list)" style="font-weight:bold;" translate="true">Supported</text></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">WPF</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Silverlight 4</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Silverlight 5</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows Phone 7 Mango</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows Phone 8</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="notsupported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Windows RT</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="notsupported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
      <tr style="vertical-align:top">
        <td style="width:181px;">
          <para styleclass="Normal (list)"><text styleclass="Normal (list)" translate="true">Test/emulation service</text></para>
        </td>
        <td style="width:82px;">
          <para styleclass="Normal (list)" style="text-align:center;"><image src="supported.png" scale="100.00%" styleclass="Normal (list)"></image></para>
        </td>
      </tr>
    </table></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Screenshot</text></para>
    <para styleclass="Normal"><image src="services_pleasewaitservice.png" scale="100.00%" styleclass="Image Caption"></image></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Showing</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;IPleaseWaitService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService.Show();</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Hiding</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;IPleaseWaitService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService.Hide();</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Showing and automatically hide</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Services_IPleaseWaitService" styleclass="Normal" translate="true">IPleaseWaitService</link><text styleclass="Normal" translate="true"> can automatically hide itself when an action is completed. To use this feature, simply pass a delegate to the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Show_1_72eac341" styleclass="Normal" translate="true">Show</link><text styleclass="Normal" translate="true"> method and the service will hide the window as soon as the delegate has completed.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;IPleaseWaitService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService.Show(()</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=&gt;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">Thread.Sleep(1500));</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Changing the status</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;IPleaseWaitService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService.UpdateStatus(&quot;new status&quot;);</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Showing a determinate please wait window</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">By default, the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="T_Catel_MVVM_Services_IPleaseWaitService" styleclass="Normal" translate="true">IPleaseWaitService</link><text styleclass="Normal" translate="true"> shows an indeterminate state (no actual progress is visible). However, both the Silverlight and WPF implementation of the service also implement the status that shows the progress of a long running action.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_UpdateStatus_1_72eac341" styleclass="Normal" style="font-style:normal;" translate="true">UpdateStatus</link><text styleclass="Normal" style="font-style:normal;" translate="true"> method can be used to show the window. The </text><text styleclass="Normal" style="font-style:italic;" translate="true">statusFormat</text><text styleclass="Normal" style="font-style:normal;" translate="true"> argument can contain &apos;{0}&apos; (represents the current item) and &apos;{1}&apos; (represents the total items). However, they can also be left out.</text></para>
    <para styleclass="Code Example"><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">var</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">=</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#ffffff;" translate="true">&#32;</text><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">GetService&lt;IPleaseWaitService&gt;();</text><br/><text styleclass="Code Example" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">pleaseWaitService.UpdateStatus(1, 5, &quot;Updating item {0} of {1}&quot;);</text></para>
    <para styleclass="Normal"><text styleclass="Normal" style="font-weight:normal; font-style:normal; color:#000000;" translate="true">The determinate version can be hidden via a call to </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Hide" styleclass="Normal" translate="true">Hide</link><text styleclass="Normal" translate="true"> or when the </text><text styleclass="Normal" style="font-style:italic;" translate="true">currentItem</text><text styleclass="Normal" style="font-style:normal;" translate="true"> argument is larger than the number of </text><text styleclass="Normal" style="font-style:italic;" translate="true">totalItems</text><text styleclass="Normal" style="font-style:normal;" translate="true">.</text></para>
    <para styleclass="Heading1"><text styleclass="Heading1" translate="true">Push/Pop</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">Sometimes, multiple view models or multiple actions use the service. It&apos;s not possible to hide the window when the first action is completed, because the user will still have to wait for the other actions to complete (without a please wait window). To implement this correctly, it is possible to use the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Push_1_72eac341" styleclass="Normal" translate="true">Push</link><text styleclass="Normal" translate="true"> and </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Pop" styleclass="Normal" translate="true">Pop</link><text styleclass="Normal" translate="true"> methods.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">The </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Push_1_72eac341" styleclass="Normal" translate="true">Push</link><text styleclass="Normal" translate="true"> method shows the window if it is not already visible and then increases an internal counter. At the start of each (asynchronous) action, the developer can call the </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Push_1_72eac341" styleclass="Normal" translate="true">Push</link><text styleclass="Normal" translate="true"> method. When the action is completed, the developer calls </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Pop" styleclass="Normal" translate="true">Pop</link><text styleclass="Normal" translate="true"> which will internally decrease the counter. If the counter hits zero (0), the window is automatically hidden.</text></para>
    <para styleclass="Normal"><text styleclass="Normal" translate="true">It is possible to hide the window, even when the internal counter is not yet zero. A call to </text><link displaytype="text" defaultstyle="true" type="topiclink" href="M_Catel_MVVM_Services_IPleaseWaitService_Hide" styleclass="Normal" translate="true">Hide</link><text styleclass="Normal" translate="true"> will reset the counter to zero and thus hide the window.</text></para>
  </body>
</topic>
